Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/032.lha/doc/root directory/Introduction

Text File | 1987-05-17 | 15.6 KB | 349 lines

            Brief Introduction to Draco

There are two disks in the Draco set. The first one, "Draco SYS" is the one
to boot from. It contains all of the executables, libraries, include files,
and much of the normal WorkBench disk stuff. There is some room on it for
stuff you might want on the disk you boot. In particular you may want to
replace Ded (Draco editor) and Ed (regular AmigaDOS editor) with
MicroEmacs. The second disk, "Draco Other" contains various pieces of
documentation and sample Draco programs. Note that the way things are set
up, the boot disk contains everything you need for compiling and running
Draco programs - your entire second drive is available for your stuff.


Short, Quick Example

To get you started real quick, here is what you need to do to enter,
compile, link, and run a simple Draco program. (Throughout, I assume you
have booted from the "Draco SYS" disk.)

    1> cd df1:
    1> ded test.d

    (you are now in the Draco editor - just enter the program as it's
    written here, then continue with the control sequence)

    proc main()void:

    writeln("Hello there world!");
    corp;

    (now write out the file and exit Ded with)

    <ESCAPE-e>

    (you should now be back in your AmigaDOS window)

    1> draco test

    (if you got any error messages, go back into the editor by again
    entering 'ded test.d' and repeating from there. You would normally
    be running the editor in the background and just writing out the
    file and switching windows, but I won't get into that here.)

    1> ex dr1 test

    ('ex' is just 'Execute' renamed, and 'dr1' is a script in 's:'
    which will link a single Draco object file with the appropriate
    libraries and startup sequence)

    1> test

    (your program now runs)


Batch Files

Directory s: contains a number of execute files which I've set up to help
out in linking Draco programs. Their names are of the form <'dr' N>, <'dr'
N 'lib'> and <'dr' N 'lib2'>, where 'N' is between 1 and 4. 'N' specifies
the number of object files (.r files produced by running the compiler) to
be linked. The first set link programs not requiring any libraries other
than the Draco run-time and I/O libraries and the Amiga dos and exec
libraries. The second set allows one library, and the third allows two. If
you need more than that, you should probably set up a "with" file for the
linker. As an example, to compile and link a program which has two source
files, "myprog1.d" and "myprog2.d", which uses the Draco I/O and memory
management routines (located in drlib:drio.lib), you would use

    1> draco myprog1 myprog2
    1> ex dr2 myprog1 myprog2

The final program is left in a file named by the first '.r' file
specified. 'ex' is just the 'Execute' command renamed.

If you wanted to link a program which uses the Amiga graphics and intuition
libraries, and had only one source file, test.d, you would use

    1> draco test
    1> ex dr1lib2 graphics intuition test

The final batch file is 'drraw', which will link a single source file which
does NOT use any of the Draco I/O or storage allocation facilities, and
does not use any Amiga library other than 'dos.library'. This is used to
link some sample programs which were written before the Draco I/O system
was ported to the Amiga.


BLink

The linker present and used by the Draco stuff is BLink, which is a
shareware product produced by The Software Distillery. You can use the
standard linker ALink instead, so long as you remove the 'smallcode'
directive from all of the batch files. I plan on porting my own linker
eventually, and it should allow the intermediate .r files to be
considerably smaller, and will also produce smaller final program files for
many programs. If you find BLink of use, you should consider a donation to
The Software Distillery.


What's on 'Draco Other'

The 'Draco Other' disk contains four directories containing sample source
files. 'misc' contains three separate programs, 'intuition', 'view', and
'cmp'. 'intuition' is a program which demonstrates the use of Intuition
Screens, Windows, Menus, etc. and a few of the RastPort oriented Graphics
calls, including a bit of animation. It has some explanatory comments in
it. 'view' is a program which demonstrates taking over the entire graphics
subsystem, temporarily suspending the Intuition user interface. I wrote it
to explore how to have a 24 line hi-resolution text screen sometimes mostly
covered by a low-resolution graphics screen. I need the combination for a
game I plan to port to the Amiga. 'cmp' is the source to the 'Cmp' program
on the "Draco SYS" disk. It is a fairly portable program (also runs on CP/
M-80) using the Draco I/O system and my CRT library. It provides full-
screen comparison of files in both binary and text modes. I find it quite
useful when working on the compiler - I make changes to the compiler, check
them out with test sources, then compile the compiler. If the resulting
version runs, I get IT to compile the compiler and compare the .r files -
they should be the same. If they aren't, 'Cmp' is very handy for finding
the differences.

To compile, link and run 'intuition', type

    1> draco intuition
    1> blink with intuition.w
    1> intuition

To compile, link and run 'view', type

    1> draco view
    1> blink with view.w
    1> view

I don't currently know why the text ViewPort jumps around when the graphics
one is sliding up and down, but my current suspicion is that the Copper
lists in the View and ViewPort are being freed and rebuilt by MakeVPort
while the hardware is still accessing them. LATER NOTE: this is indeed the
case - in another version, I've double buffered the copper lists and the
bouncing goes away.

To compile, link and run 'cmp', type

    1> draco cmp
    1> ex dr1lib crt cmp
    1> cmp -?

The second directory, 'quest', contains the complete source for the driver
portion of a CRT/text oriented adventure game. It is written in a fairly
portable way using Draco I/O constructs and the CRT library. The same
source (except for the CRT_Initialize call) runs on CP/M-80. What is needed
here is a useful scenario. To compile, link, and run 'quest', type

    1> draco qmain qparse qcrt qlist
    1> blink with q.w
    1> quest

Note that it currently only uses a 24 line window. You can change 'qcrt' to
call CRT_Initialize with different parameters if you want. When highlighted
'M O R E' appears down the right side of the text subwindow, pressing any
key will allow it to continue. All output is automatically word wrapped and
paginated by the quest output routines. Some commands that the little test
scenario understands are:

    n, north, s, south, e, east, w, west, pick up, put down, look, long, dump

'dump' will dump out the parser's internal structures, including the
grammar it is accepting. Such a command would not normally be present.

The third directory, 'rawSamples', contains programs that I wrote before I
had ported the I/O library. Thus, they don't use Draco's I/O constructs but
instead directly call the AmigaDOS I/O routines. The four programs are
'entab', 'detab', 'uuencode' and 'uudecode'. 'entab' and 'detab' both strip
carriage-returns from files, stop when they hit the CP/M EOF character
(CNTL-Z, which is used by the XMODEM protocol) and either change blanks to
standard 8-column tabstops when possible, or expand such tabstops into
blanks. (If you are going to use the standard Amiga editor, Ed, you will
want to expand tabs, since Ed doesn't handle them properly.) 'uuencode' and
'uudecode' are standard utilities for encoding and decoding binary files as
character data which can be transmitted as mail over computer networks,
etc. Note that they use the newer form of the 'uuencode' protocol, which
uses graves (`) instead of blanks. All four programs are linked using
'drraw'. E.g.

    1> draco entab
    1> ex drraw entab

The fourth directory, 'samples', contains simple programs illustrating
various aspects of the language. The 'Read.Me' file in that directory
explains a bit about each one.


Exec Libraries

The Amiga documentation shows that the Exec routine "OpenLibrary" is to be
used to open either a resident or disk based library. This returns a
pointer to the library node, which is to be in A6 whenever an entry from
that library is called. In C, the library node pointer is supposed to be
assigned to a specifically named variable which the assembler interface
stubs access as a global to get the value to pass in A6. Draco doesn't have
such named global variables, so a different technique is used. The 'convfd'
program, which takes the ".fd" files and produces the interface libraries,
also produces private versions of "OpenLibrary" and "CloseLibrary" for each
library. They are called "OpenXXXLibrary" and "CloseXXXLibrary", where XXX
is the name of the library. "OpenXXXLibrary" is passed the desired version
number as a 'ulong' and returns the library node pointer. For example, to
open the Intuition library, the following would be declared:

    extern
    OpenIntuitionLibrary(ulong version)*IntuitionBase_t,
    CloseIntuitionLibrary()void;

For resident libraries (those for which there isn't a ".library" file in
the "libs:" directory), the close call isn't really needed, but should be
used for compatibility with future Amiga systems.

A couple of the devices in the Amiga system are similar to libraries in
that they have some independent routines, accessed in a library-like
manner, associated with them. ".fd" files exist for them, and 'convfd'
produces interface routines. With these calls, the device node is used in a
similar way, but the standard "OpenDevice" call only returns it indirectly,
in the IO request block. To use these in Draco, use "OpenDevice" and
"CloseDevice" as the RKM indicates. If you want to call the related,
library-like functions, you must first call "SetXXXDevice", where XXX is
the device name. You pass it the Device pointer extracted from the IO
request block. Sample declarations (for timer.device):

    extern
    SetTimerDevice(*Device_t timerDevice)void,
    SubTime(*TimeVal_t dest, source)void;

Some of the resources (e.g. disk.resource, cia.resource) operate in an
analagous manner.


Draco Libraries

Proper opening/closing is also required for the Draco specific libraries.
The startup file that is linked in by the batch files described previously
will automatically initialize the commonly used Draco libraries. Thus, you
can use Draco's I/O, storage allocation and parameter accessing libraries
without any special setup. The problem with this scheme is that it forces
all programs to contain most of the referenced libraries, because BLink
(and ALink) insists on loading all routines from any unit from which any
routine is needed. If I ever get around to porting my linker, programs
produced with Draco using these libraries will become considerably smaller.
You can set up your own batch files (or 'with' linker files) which
reference the alternate startup file (drlib:drstart0.o instead of drlib:
drstart.o). If you do this, you must be aware of the following needs:

Any use of a Draco I/O construct or associated I/O call requires that the
I/O library be initialized. This is done by calling

    _IO_initialize();

This routine will open the DOS library also. Any use of the new/free
constructs or the Malloc/Mfree calls requires that the storage allocation
sub-library be initialized via

    _M_initialize();

This routine will open the Exec library (since that's where AllocMem is).
Any use of the parameter accessing routines requires a previous call to

    _Pars_initialize();

Regardless of which startup file you are using, any use of the CRT terminal
library requires that it be initialized (and a CON: window created for it
to use). The CON: window needs to be closed when you are done, also. These
jobs are handled by

    extern
    CRT_Initialize(*char windowName; ushort lineCount, columnCount)void,
    CRT_Terminate()void;

which are declared (along with all of the other CRT routines) in 'include:
crt.g'. The 'windowName' is used as the window title, and the line and
column counts are the text line and column counts desired. On an interlaced
screen, sizes from 16 lines to 50 lines and 32 columns to 80 columns are
supported. The forms input routines in the CRT library are a separate
sublibrary which must be initialized separately if needed. This is done by

   _F_initialize();

If the forms routines are used, the storage allocator must also be set up,
as previously described.

To summarize, most Draco programs will use one of the normal batch files
(or a with file similarly set up) to link programs. These programs will
use drstart.o to start up, which will automatically call _IO_initialize,
_M_initialize and _Pars_initialize. If you want to cut down on program
size, don't use the I/O or storage allocation facilities in Draco, link
using drstart0.o, and talk directly to AmigaDOS yourself. (Interface
routines for AmigaDOS are in dos.lib and declarations are in include:
libraries/dos.g and dosextens.g.)


Making Your Own Boot Disks

The only things that you really need on a boot disk are an assign of
'include:' to where the include directories are; an assign of 'drlib:'
to where the '.lib' files are (and dracoErrors and the startup '.o'
files); and a stack size of at least 16000.


Current State of this Distribution

    compiler - types 'float' and 'lfloat' are predefined, but if you try to
    do much with them, you will probably crash the compiler. Operator
    types are totally untested in this compiler and will also probably
    crash it. There is still at least one bug associated with undefined
    symbols - if the compiler aborts with 'program buffer overflow'
    after messages about undefined symbols or something similar, just
    try compiling again after fixing the previous errors. Code quality
    is not so good. It's about on par with Lattice or Aztec if you
    cripple them by not using register variables and force long
    addressing modes (which is what the Draco compiler currently does).
    Also, everything is stacked and unstacked on each procedure entry/
    exit. A peepholer is needed, especially for some MOVE/MOVE stuff.

    Ded editor - needs proper support for multiple windows into a single
    file. The documentation needs properly updating to describe the
    multiple windows. File reading/writing is slow (it goes through the
    standard Draco I/O stuff - I should either rewrite it to use the
    native AmigaDOS calls or put code into LineRead and LineWrite so
    that they can directly access the file's buffer). Long file names
    are not handled at all (they will mess up the display). There are
    problems with special characters (including tabs) in input lines -
    the editor gets confused by quotes and doesn't expand them because
    it thinks they are inside a string. I'm not sure what to do about
    this one. No menu or mouse support at all. About the only one that
    I personally would find useful is using the mouse to move the text
    cursor. Still some problems with the definition of "words". Again,
    I'm not sure how to fix this - the rules are already pretty tricky.
    Still some minor problem with INDENT and OUTDENT.

    Quest - needs a scenario. Needs graphicizing.

LAST MINUTE ADDITION:

    While waiting for Commodore to OK this distribution's including my
translated versions of their copyrighted include files, I and a friend got
ambitious and started implementing Old Empire in Draco for the Amiga.
We're most of the way there, but its not done yet. We've actually been
playing for about 5 weeks during the development phase (makes a good
incentive to add new commands). So, directory 'Empire' contains the binary
for our latest version (last changed last night), along with some rough
and ready documentation and a couple versions of the world-builder program.
It's quite playable as it is, but there are bound to be bugs. Let us know
about them, as well as any you find in the Draco stuff. Have fun!